Add Agent.to_web() method and web chat UI #3456

dsfaccini · 2025-11-17T18:27:44Z

web-based chat interface for Pydantic AI agents

new module pydantic_ai.ui.web
new method Agent.to_web()

fastapi

app = create_chat_app(agent)
the following endpoints come preconfigured:
- GET / and /:id - serve the chat UI
- POST /api/chat - Main chat endpoint using VercelAIAdapter
- GET /api/configure - Returns available models and builtin tools
- GET /api/health - Health check
- NOTE: I'm counting on FastAPI to complain if the user tried adding conflicting routes, otherwise we could add a warning on the respective docs.

options and example

NOTE: the module for options is currently pydantic_ai.ui.web.

pre-configured model options:
- anthropic:claude-sonnet-4-5
- openai-responses:gpt-5
- google-gla:gemini-2.5-pro
supported builtin tools:
- web_search
- code_execution
- image_generation

# app.py
import logfire
from pydantic_ai import Agent

logfire.configure(send_to_logfire='if-token-present')
logfire.instrument_pydantic_ai()

agent = Agent('openai:gpt-5')

@agent.tool
def get_weather(city: str) -> str:
    return f"The weather in {city} is sunny"

app = agent.to_web()

logfire.instrument_fastapi(app, capture_headers=True)

# Run with: uvicorn app:app

testing

7 tests in tests/test_ui_web.py

notes

UI is served from CDN: @pydantic/[email protected]
Uses Vercel AI protocol for chat streaming
TODO: add clai web command to launch from the CLI (as in uvx pydantic-work without the whole URL magic)
TODO: should I add a new doc at docs/ui/to_web.md? I'd also reference this in docs/ui/overview.md and docs/agents.md

EDIT: if you try it out it's worth noting that the current hosted UI doesn't handle ErrorChunks, so you will get no spinner and no response when there's a model-level error and fastapi will return a 200 any way.
This will happen for instance when you use a model for which you don't have a valid API key in your environment
I opened a PR for the error chunks here pydantic/ai-chat-ui#4.

Closes #3295

pydantic_ai_slim/pydantic_ai/ui/web/app.py

clai/clai/chat/agent_discovery.py

DouweM · 2025-11-18T18:02:47Z

pydantic_ai_slim/pydantic_ai/_cli.py

    args = parser.parse_args(args_list)

+    # Handle web subcommand
+    if args.command == 'web':


Maybe it should be --web so it doesn't conflict with the prompt arg?

DouweM · 2025-11-18T18:03:24Z

pydantic_ai_slim/pydantic_ai/agent/__init__.py


        self._get_toolset().apply(_set_sampling_model)

+    def to_web(self) -> Any:


We're gonna need some args here -- have a look at the to_a2a and to_ag_ui methods. Not saying we need all of those args, but some may be useful

pydantic_ai_slim/pydantic_ai/agent/__init__.py

DouweM · 2025-11-18T18:06:05Z

pydantic_ai_slim/pydantic_ai/ui/web/agent_options.py

@@ -0,0 +1,75 @@
+"""Model and builtin tool configurations for the web chat UI."""


The goal is for the developer to be able to pass a list of models and builtin tools to to_web, instead of anything hard-coded they may not have keys for. We'd need a new field like supported_builtin_tools on ModelProfile to store for each model/provider which builtin tools it supports. Then we can automatically generate the structures below based on the user-provided data and which tools work with which models.

pydantic_ai_slim/pydantic_ai/ui/web/agent_options.py

DouweM · 2025-11-18T18:08:11Z

pydantic_ai_slim/pydantic_ai/ui/web/app.py

+from .agent_options import AIModel, BuiltinTool
+from .api import create_api_router
+
+CDN_URL = 'https://cdn.jsdelivr.net/npm/@pydantic/ai-chat-ui/dist/index.html'


I think we should pin a specific version, in case we make backward-incompatible changes at some point

DouweM · 2025-11-18T18:08:47Z

pydantic_ai_slim/pydantic_ai/ui/web/app.py

+    async def index(request: Request):  # pyright: ignore[reportUnusedFunction]
+        """Serve the chat UI from CDN."""
+        async with httpx.AsyncClient() as client:
+            response = await client.get(CDN_URL)


We should cache this somewhere

DouweM · 2025-11-18T18:09:22Z

tests/test_ui_web.py

+        response = client.get('/api/configure')
+        assert response.status_code == 200
+        data = response.json()
+        assert 'models' in data


Use a snapshot please :)

dsfaccini · 2025-11-20T17:04:52Z

I just pushed an update to this removing the AST aspect and (hopefully) fixing the tests so they pass in CI

haven't addressed the comments yet so it isn't reviewable yet

- consolidate UI agent-options - fix cli commands - cache UI on client and server - offer choosable UI versions

- rename config vars to be nicer

add Agent.to_web() method and web chat UI module pydantic#3295

1cfa48e

dsfaccini commented Nov 17, 2025

View reviewed changes

pydantic_ai_slim/pydantic_ai/ui/web/app.py Outdated Show resolved Hide resolved

dsfaccini added 5 commits November 17, 2025 14:28

add "web" group

d83caa5

try import create_chat_app

bfffd4b

fix tests to run on CI

055e120

fix example to use tool_plain

6bc8b16

add clai web - tested with uv run clai web

32f7e1d

DouweM requested changes Nov 18, 2025

View reviewed changes

DouweM self-assigned this Nov 18, 2025

DouweM added the awaiting author revision label Nov 18, 2025

wip: remove agent discovery and fix tests

cf0e177

dsfaccini added 10 commits November 20, 2025 12:09

rename command

e7f44eb

rename function

c4ffde3

- define builtin tool ids

0595c27

- consolidate UI agent-options - fix cli commands - cache UI on client and server - offer choosable UI versions

fix tests

0d24941

- update CLI commands and improve agent loading mechanism

e5b30c2

- rename config vars to be nicer

Merge branch 'main' into clai-chat

f2dd19a

import sorting

8ca7a27

more import sorting

fa3bb5f

covergae?

e45c93f

Merge upstream/main into clai-chat

f90b570

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add Agent.to_web() method and web chat UI #3456

Add Agent.to_web() method and web chat UI #3456

dsfaccini commented Nov 17, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

DouweM Nov 18, 2025

Uh oh!

DouweM Nov 18, 2025

Uh oh!

Uh oh!

DouweM Nov 18, 2025

Uh oh!

Uh oh!

DouweM Nov 18, 2025

Uh oh!

DouweM Nov 18, 2025

Uh oh!

DouweM Nov 18, 2025

Uh oh!

dsfaccini commented Nov 20, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		self._get_toolset().apply(_set_sampling_model)

		def to_web(self) -> Any:

		@@ -0,0 +1,75 @@
		"""Model and builtin tool configurations for the web chat UI."""

Add Agent.to_web() method and web chat UI #3456

Are you sure you want to change the base?

Add Agent.to_web() method and web chat UI #3456

Conversation

dsfaccini commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

fastapi

options and example

testing

notes

Uh oh!

Uh oh!

Uh oh!

DouweM Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

DouweM Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

DouweM Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

DouweM Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

DouweM Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

DouweM Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

dsfaccini commented Nov 20, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dsfaccini commented Nov 17, 2025 •

edited

Loading